Content IA - Web APIs

[bsmth]

This discussion is about MDN information architecture changes planning for this year, specifically the Web API docs under /Web/API/*.

Based on IA work in other areas, we're applying content categorization of reference material separate from guides, tutorials, and how-tos. For the API docs, this means consolidating guide material and reference docs in a related parent.

I've shared some ideas of how to apply this to Web API docs internally with content & eng, and in the editorial calls to gather feedback from other writers and maintainers.

Background and rationale of the site-wide initiative is discussed at https://github.com/orgs/mdn/discussions/776

Purpose of this discussion

I want to share a proposal that incorporates feedback already based on what I've informally shared to date. This discussion is for course correction, in case there are other concerns or ideas that anyone hasn't shared yet, or other blockers you may spot.

Proposal

Currently, we have a relatively flat hierarchy in the API section, like:

./files/en-us/web/api
├── abortcontroller
├── abortsignal
├── absoluteorientationsensor
├── abstractrange
…
├── xrwebglsubimage
└── xsltprocessor

1183 directories

I'm proposing we move all interfaces, events, and guides under the API in which they're defined. I've sketched out a sheet for interfaces which you can request access for to see the idea. This would move all interfaces into 143 directories with web-api-overview page type.

Example API

For the Window Management API, we can look at the current state:

files/en-us/web/api/window_management_api/
├── index.md
├── multi-screen_origin
│   └── index.md
└── using
    └── index.md

files/en-us/web/api/screendetailed
├── availleft
│   └── index.md
├── availtop
│   └── index.md
├── devicepixelratio
│   └── index.md
├── index.md
├── isinternal
│   └── index.md
├── isprimary
│   └── index.md
├── label
│   └── index.md
├── left
│   └── index.md
└── top
    └── index.md

files/en-us/web/api/screendetails
├── currentscreen
│   └── index.md
├── currentscreenchange_event
│   └── index.md
├── index.md
├── screens
│   └── index.md
└── screenschange_event
    └── index.md

The proposed structure would be:

files/en-us/web/api/window_management_api
├── guides
│   ├── index.md
│   ├── multi-screen_origin
│   │   └── index.md
│   └── using
│       └── index.md
├── index.md
└── reference
    ├── index.md
    ├── screendetailed
    │   ├── availleft
    │   │   └── index.md
    │   ├── availtop
    │   │   └── index.md
    │   ├── devicepixelratio
    │   │   └── index.md
    │   ├── index.md
    │   ├── isinternal
    │   │   └── index.md
    │   ├── isprimary
    │   │   └── index.md
    │   ├── label
    │   │   └── index.md
    │   ├── left
    │   │   └── index.md
    │   └── top
    │       └── index.md
    └── screendetails
        ├── currentscreen
        │   └── index.md
        ├── currentscreenchange_event
        │   └── index.md
        ├── index.md
        ├── screens
        │   └── index.md
        └── screenschange_event
            └── index.md

Feedback

The feedback I've gotten already is much appreciated. If you've missed a chance to share thoughts of concerns, you're welcome to do so here.

Unknowns

Some unknowns so far are how to elegantly handle extensions, for instance, we have Web/API/Window/getScreenDetails, which we may consider moving, too:

files/en-us/web/api/window_management_api
├── guides
├── index.md
└── reference
    ├── index.md
    ├── screendetailed
    ├── screendetails
    └── window
        ├── getscreendetails
        │   └── index.md
        └── index.md

It's a tricky problem to solve, especially given site nav changes when going from Window to Window Management API and back.

Updates

I'll update this discussion as this progresses, with info on when we'll start and how to get involved.

Other discussions / issues

• OWD project: Organise Web APIs openwebdocs/project#76
• "API structure conventions: inheritance": https://github.com/orgs/mdn/discussions/205

---

Thanks :)

[Elchi3]

Thanks for putting this together, Brian! I'll share the feedback that I already voiced in the MDN content call on Monday.

I'm super happy about the adoption of content categorization ala diataxis where reference material is separate from guides, tutorials, and how-tos. So good!

I also really like how in other content areas reference pages are now neatly organized by the type of thing they are:

• HTTP headers (Web/HTTP/Reference/Headers/allHeaders)
• HTML elements (Web/HTML/Reference/Elements/allElements)
• JS Global Objects (Web/JavaScript/Reference/Global_Objects/allGlobalObjects)
• etc

The new CSS restructuring proposal is consistent with that, too:

• CSS Properties (Web/CSS/Reference/Properties/allProperties)
• CSS Selectors (Web/CSS/Reference/Selectors/allSelectors)
• etc

However, I find it surprising that this proposal is not following that model. I would have expected:

• API interfaces (Web/API/Reference/Interfaces/allInterfaces)
• WebGL Extensions (Web/API/Reference/WebGL_extensions/allWebGLExtensions)
• etc

I think there is a need to put together "Groups of interfaces" that form a "Module" (although, I'm not sure "Module" is a good terminology, in web-features, we call these things features and groups). In the CSS reorg proposal these modules live separately and the reference pages are not put under their module. In JavaScript, the JS Guide categorizes things, but again the JS reference pages are not sorted below these categories. Same in HTML and HTTP.

I think there is a need for these higher-level groups, or modules or however we want to name this. I'm just not sure what the reasons are for having them in the structure in API/. I think I would say, these groups could live one level higher up as often they are not just about a collection of API interfaces, but rather a collection of API interfaces, CSS properties, HTML elements, HTTP headers, etc.

Examples include:

• Web Components. Sure, there are API aspects of this, and per your proposal there is: Web/API/Web_components/Reference, but what about the HTML elements, the CSS selectors, etc. that all form the "Web Components" group. Will there be a second hierarchy Web/Web_Components, and then another CSS modules for the CSS parts of this?
• Fullscreen API. Very similar. Has API parts, CSS parts, HTML parts, HTTP parts.
• SVG DOM API, HTML DOM API. I would say that guide, tutorial, how-to material that I guess this proposal is moving under Web/API/HTML_DOM_API and Web/API/SVG_API could also live under Web/HTML/ and Web/SVG directly. No need to split between the API part and the other language parts of this.

I could go on and find more examples. I haven't done the work of playing this through for everything. I can, though, to try to illustrate my point in a sheet if you like, but basically, yes, let's come up with groups of things that make sense but in my view it would be good to do that more generally and not just within the API tree. There I would love to stick to the structure that MDN has everywhere else and that you all worked on and made very consistent over the last few months.

I also think this would avoid the problem of how to elegantly handle extensions as they would still live in a monolithic api/reference/Interfaces structure. A more higher up Window Management tree can then pick from any reference material it needs to pick from (API interfaces, HTTP headers, ...) and give the overview, guides, how-tos, tutorials for that "API" (API in the more generic meaning and not just in the meaning of a collection of WebIDL interfaces).

[wbamberg]

Some unknowns so far are how to elegantly handle extensions, for instance, we have Web/API/Window/getScreenDetails, which we may consider moving, too:

files/en-us/web/api/window_management_api
├── guides
├── index.md
└── reference
    ├── index.md
    ├── screendetailed
    ├── screendetails
    └── window
        ├── getscreendetails
        │   └── index.md
        └── index.md

It's a tricky problem to solve, especially given site nav changes when going from Window to Window Management API and back.

Without trying to address Florian's comment yet, I think it's quite important for all the members of every interface to be documented together. So I mean if I'm looking at Window, I get to see all the members of Window. That means we should not document extensions separate from the "main" interface, as in the proposal quoted above. I think it would be extremely confusing to do this. It would be better to do something like what we do now, and have extensions to other interfaces handled as cross-references:

[bsmth]

That means we should not document extensions separate from the "main" interface, as in the proposal quoted above. I think it would be extremely confusing to do this.

You're probably right, and I think this is more what we display in sidebars v where files are living

[chrisdavidmills]

APIs are tricky. In a similar fashion to CSS, we want to create more of a hierarchy and divide up the current monolithic directory. However, there isn't quite as obvious a set of reference groupings with APIs as there is with CSS.

Having thought about all this, I have to say that I agree with @Elchi3 that we should follow the same pattern as the CSS reorg if at all possible. To me, this would look like:

API/
  Reference/
    Interfaces/
    WebGL_extensions/
    Some_other_ref_thing/
    ...
  APIs/
  Guides/
  How_tos/

The biggest questions here, IMO, are:

1. What do we call "APIs"? This is kind of analogous to "Modules" in CSS, and it gives us a nice opportunity to organize features by API, list extensions and related features, and list non-interface stuff that is of equal importance, in cases like the ones @Elchi3 brought up, like Web components and Fullscreen API. We should update the sidebars for these pages so they can also list related HTML elements/attributes, CSS properties, HTTP headers, etc.

   But again, the biggest question is, IMO, What do we call "APIs"? A URL structure of API/APIs is pretty crappy. Maybe WebAPIs/API would work better? I don't know at present.

2. How would we organize the Guides directory? By API would be fine, I guess, although generally when I document a new API, I always just include a basic "Using..." guide below the API landing page, which makes the separate Guides directory almost seem a little pointless. However, in going ahead with this organization, we have a great opportunity to organize the guides into nice task-based categories like Media, 2D and 3D graphics, Network, Performance, Client-side storage, Animation, etc. I'm not yet sure whether we would do that by different directories, or just on the landing page, but it is a good problem to think about.

   In the Discord discussion, @wbamberg mentions "try to define a relatively small number of high-level categories for things" and "it would so great to present users with a higher-level view of web APIs." I agree. If we could do this just inside the Guides section, that would be a great achievement.

I also agree with what @Rumyra is saying, that CSS and APIs are different beasts. We shouldn't think of CSS "Modules" as being the same thing as "APIs". I actually think the API landing pages are more useful than the CSS module landing pages — a bit more intuitive for those wishing to browse by spec grouping. For those not as familiar with the spec content who want to browse by pure functionality grouping, having solid Guide organization would be the way to solve that, imo.